package org.flexthinker.binding.ui.form.binding
{
    import flash.display.DisplayObject;

    /**
     * Interface describing a strategy to discover visual fields belonging to a form,
     * so that they can be used for auto-bind.
     */
    public interface BindingFieldFinder
    {
        /**
         * Finds the visual fields belonging to the form that can be used for
         * binding.
         * <p>
         *     Identifying the fields might not be just a one time operation,
         *     as new fields may be added into the UI at a later time.
         *     Some implementations may choose to listen for events to identify
         *     new fields that could be used for binding.
         *     </p>
         * @return
         *      List of <code>DisplayObject</code> elements.
         */
        function getBindableFields():Vector.<DisplayObject>;

        /**
         * Resets the finder to an initial state.
         * If the finder was actively listening for some events,
         * this method should reset everything back, freeing the memory,
         * releasing variables, removing event listeners.
         */
        function reset():void;

        /**
         * Sets the instance of the form that will be used to search for fields.
         * @param value
         *          Visual form.
         */
        function setForm( value:Object ):void;

        /**
         * Adds a listener to be called when fields become available or get removed.
         * @param listener
         *          <code>BindingFieldFinderListener</code> instance
         */
        function addFinderListener( listener:BindingFieldFinderListener ):void;

        /**
         * Removed an added listener.
         * @param listener
         *          <code>BindingFieldFinderListener</code> instance
         */
        function removeFinderListener( listener:BindingFieldFinderListener ):void;

        /**
         * Clears all added listeners.
         */
        function removeAllListeners():void;
    }


}
